classdef dotsDrawable < dotsAllManagedObjects
    % @class dotsDrawable
    % Superclass for drawable graphics objects.
    %
    % dotsTheDrawablesManager creates and organizes subclasses of
    % dotsDrawable.  Programs that might need to use dotsDrawable* objects
    % with a remote server should use dotsTheDrawablesManager to create
    % instances of dotsDrawable subclasses and to call their methods.
    %
    % Subclasses should redefine the draw() method to use specific OpenGL
    % drawing commands.  Most drawing commands should assume units of
    % degrees of visual angle, with the origin centered on the display.
    % This is because dotsTheScreen configures OpenGL to do a
    % pixels-per-degree transformation automatically.  This works for
    % commands that deal with the positions of points, lines, and
    % polygons.
    % @details
    % A few commands may need to assume units of pixels.  For example the
    % "size" at which OpenGL draws a single point may need to be expressed
    % in pixels.
    %
    % Subclasses should may also redefine the prepareToDrawInWindow()
    % method.  This should do any one-time or infrequent set up to enable
    % or optimize the behavior of draw().  dotsTheDrawablesManager
    % automatically invokes prepareToDrawInWindow() for each of the objects
    % in its active group:
    %   - during activateGroup(), if an OpenGL drawing window is open
    %   - during openScreenWindow()
    %   .
    %
    % @ingroup drawable
    
    properties (SetObservable = true)
        % true or false, whether to draw() this object
        isVisible;
        
        % foreground color, [L], [LA], [RGB], or [RGBA], in [0-255]
        % @details
        % Automatically opts in to share via dotsTheSwitchboard.
        foregroundColor;
        
        % a background color, [L] [LA] [RGB] [RGBA], 0-255
        % @details
        % Automatically opts in to share via dotsTheSwitchboard.
        backgroundColor;
    end
    
    properties (SetObservable = false)
        % pixel dimensions of the current drawing window [x y x2 y2]
        % @details
        % Automatically opts in to share via dotsTheSwitchboard.
        windowRect;
        
        % Hz frame rate of the current drawing window
        % @details
        % Automatically opts in to share via dotsTheSwitchboard.
        windowFrameRate;
        
        % system path to locate image files
        % Use dotsTheMachineConfiguration to specify a machine-specific
        % imagesPath.
        imagesPath;
    end
    
    methods
        % Constructor takes no arguments.
        function self = dotsDrawable
            self = self@dotsAllManagedObjects;
            
            % share drawing-related properties
            self.isVisible = true;
            dotsTheSwitchboard.sharePropertyOfObject('isVisible', self);
            dotsTheSwitchboard.sharePropertyOfObject('foregroundColor', self);
            dotsTheSwitchboard.sharePropertyOfObject('backgroundColor', self);
            
            % shared certain screen-related properties
            theScreen = dotsTheScreen.theObject;
            dotsTheSwitchboard.shareManyPropertiesOfObject( ...
                theScreen.sharedProperties, self);
        end
        
        % Do any pre-draw setup that requires an OpenGL drawing window.
        function prepareToDrawInWindow(self)
        end
        
        % Draw() or not, depending on isVisible and possibly other factors.
        function mayDrawNow(self)
            if self.isVisible
                self.draw;
            end
        end
        
        % Subclass must redefine draw() to draw graphics.
        function draw(self)
        end
        
        % Shorthand to set isVisible=true.
        function show(self)
            self.isVisible = true;
        end
        
        % Shorthand to set isVisible=false.
        function hide(self)
            self.isVisible = false;
        end
    end
end